.\"     # DS - begin display
.de DS
.RS
.nf
.sp
..
.\"     # DE - end display
.de DE
.fi
.RE
.sp
..
.TH rlm_unbound 5 "8 July 2013" "" "FreeRADIUS Module"
.SH NAME
rlm_unbound \- FreeRADIUS Module
.SH DESCRIPTION
Each instance of \fIrlm_unbound\fP provides an embedded DNS client
for performing DNS lookups.  Each instance may be configured separately
to query different DNS horizons, change DNSSEC options, etc.
.PP
The module is primarily intended for use by other modules through
internal APIs, and so, instances should be initialized earlier than
those modules which use them.  Each instance does also provide some
xlat functionalities for general use and for troubleshooting.
.PP
Each instance of rlm_unbound may take the following parameters:
.IP filename
This file must exist and must point to a valid libunbound configuration file.
The default is ${raddbdir}/mods-config/unbound/default.conf.
.IP timeout
While libunbound provides an asynchronous API for internal use, using any xlat
is done synchronously from the perspective of unlang.  This value limits the
amount of time a request will wait for DNS to respond, after which the xlat
will fail.  The default is 3000 milliseconds.  This setting is independent of
any libunbound configuration values.
.PP
An instance named, for example, "dns" will provide the following xlat
functionalities:
.IP %dns(<owner>, <record type>[, <limit>])
Perform the lookup of <record type> against <owner> returning up to
<limit> results.  The returned data type is appropriate to the record
type being queried.
.IP %dns(<owner>, A)
Performs an A lookup for the owner name, returning the results as IPv4
addresses.
.IP %dns(<owner>, AAAA)
Performs an AAAA lookup for the owner name, returning the results as IPv6
addresses.
.IP %dns(<owner>, PTR)
Performs a PTR lookup for the owner.
.IP %dns(<owner>, MX, 1)
Performs an MX lookup for the owner, returning just the first result.
.PP
.SH CAVEATS
Logging from rlm_unbound can be problematic, especially if more than one
instantiation of the module is used.  This is due to the need for additional
features in the underlying libunbound which hopefully will be enhanced over
time.
.PP
There is a potential for a FreeRADIUS server using rlm_unbound to either
fail to terminate cleanly (leaving zombie processes, failing to clean up
other modules, and hanging after a SIGTERM until a SIGKILL is sent) or
to fail valgrind checks during termination when run with -m.  Likewise this
problem will rely on upstream enhancements before it can be fixed, and the
exact behavior may change in interim releases until then.
.PP
The logging behavior of rlm_unbound may vary depending on whether
FreeRADIUS is compiled with support for threads.
.PP
.SH FILES
.I /etc/raddb/modules-available/rlm_unbound
.I /etc/raddb/modules-config/unbound/
.PP
.SH "SEE ALSO"
.BR radiusd (8),
.BR radiusd.conf (5)
.BR libunbound (3)
.BR unbound.conf (5)
.SH AUTHOR
Brian S. Julin, bjulin@clarku.edu

